Medienbenachrichtigungen und Wiedergabesteuerung mit der Media Session API anpassen

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Unter anderem erfahren Sie, wie Sie Hardware-Medientasten einbinden und Medienbenachrichtigungen anpassen.

François Beaufort

Mit der Media Session API können Nutzer sehen, was gerade in ihrem Browser wiedergegeben wird, und die Wiedergabe steuern, ohne zur Seite zurückzukehren, auf der sie gestartet wurde. Webentwickler können diese Funktion über Metadaten in benutzerdefinierten Medienbenachrichtigungen, Medienereignisse wie Wiedergabe, Pausieren, Suchen, Titelwechsel und Videokonferenzereignisse wie Stummschalten/Aktivieren des Mikrofons, Ein-/Ausschalten der Kamera und Auflegen anpassen. Diese Anpassungen sind in verschiedenen Kontexten verfügbar, z. B. in Mediahubs auf Computern, in Medienbenachrichtigungen auf Mobilgeräten und sogar auf Wearables. Diese Anpassungen werden in diesem Artikel beschrieben.

Media Session API

Die Media Session API bietet mehrere Vorteile und Funktionen:

• Hardware-Medientasten werden unterstützt.
• Medienbenachrichtigungen können auf Mobilgeräten, Computern und gekoppelten Wearables angepasst werden.
• Der Mediahub ist auf Computern verfügbar.
• Die Mediensteuerung auf dem Sperrbildschirm ist auf ChromeOS und auf Mobilgeräten verfügbar.
• Die Steuerelemente für das Bild-im-Bild-Fenster sind für die Audiowiedergabe, Videokonferenzen und Präsentationen von Folien verfügbar.
• Die Assistant-Integration ist auf Mobilgeräten verfügbar.

Einige dieser Punkte werden anhand von Beispielen veranschaulicht.

Beispiel 1:Wenn Nutzer die Medientaste „Nächster Titel“ auf ihrer Tastatur drücken, können Webentwickler diese Nutzeraktion verarbeiten, unabhängig davon, ob sich der Browser im Vordergrund oder im Hintergrund befindet.

Beispiel 2:Wenn Nutzer einen Podcast im Web hören, während ihr Gerätebildschirm gesperrt ist, können sie über die Mediensteuerung auf dem Sperrbildschirm weiterhin auf das Symbol „Zurückspulen“ tippen, damit Webentwickler die Wiedergabezeit um einige Sekunden zurücksetzen.

Beispiel 3:Wenn Nutzer Tabs haben, auf denen Audio wiedergegeben wird, können sie die Wiedergabe auf dem Computer ganz einfach über den Mediahub beenden, damit Webentwickler den Status löschen können.

Beispiel 4:Wenn Nutzer an einem Videoanruf teilnehmen, können sie im Fenster „Bild-im-Bild“ auf die Schaltfläche „Mikrofon ein-/ausschalten“ klicken, um zu verhindern, dass die Website Mikrofondaten empfängt.

Dies geschieht über zwei verschiedene Schnittstellen: die MediaSession- und die MediaMetadata-Schnittstelle. Mit der ersten können Nutzer die Wiedergabe steuern. Zweitens: Wie Sie MediaSession mitteilen, was gesteuert werden soll.

Das Bild unten zeigt zur Veranschaulichung, wie diese Oberflächen sich auf bestimmte Mediensteuerungen beziehen, in diesem Fall eine Medienbenachrichtigung auf einem Mobilgerät.

Nutzer darüber informieren, was gerade läuft

Wenn auf einer Website Audio oder Video abgespielt wird, erhalten Nutzer automatisch Medienbenachrichtigungen, entweder im Benachrichtigungs-Tray auf Mobilgeräten oder im Medienhub auf dem Computer. Der Browser versucht, geeignete Informationen anzuzeigen, indem er den Titel des Dokuments und das größte Symbolbild verwendet, das er finden kann. Mit der Media Session API können Sie die Medienbenachrichtigung mit umfassenderen Medienmetadaten wie Titel, Künstlername, Albumname und Artwork anpassen, wie unten dargestellt.

Chrome fordert den „vollständigen“ Audiofokus an, um nur dann Medienbenachrichtigungen anzuzeigen, wenn die Mediendauer mindestens 5 Sekunden beträgt. So werden Benachrichtigungen nicht bei nebensächlichen Geräuschen wie Klingeln angezeigt.

// After media (video or audio) starts playing
await document.querySelector("video").play();

if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Never Gonna Give You Up',
    artist: 'Rick Astley',
    album: 'Whenever You Need Somebody',
    artwork: [
      { src: 'https://via.placeholder.com/96',   sizes: '96x96',   type: 'image/png' },
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/192', sizes: '192x192', type: 'image/png' },
      { src: 'https://via.placeholder.com/256', sizes: '256x256', type: 'image/png' },
      { src: 'https://via.placeholder.com/384', sizes: '384x384', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  });

  // TODO: Update playback state.
}

Nach Ende der Wiedergabe müssen Sie die Mediensitzung nicht „freigeben“, da die Benachrichtigung automatisch verschwindet. Beachte aber, dass navigator.mediaSession.metadata verwendet wird, wenn die nächste Wiedergabe beginnt. Daher ist es wichtig, sie zu aktualisieren, wenn sich die Quelle der Medienwiedergabe ändert, damit in der Medienbenachrichtigung relevante Informationen angezeigt werden.

Bei den Medienmetadaten gibt es einige Dinge zu beachten.

• Das Artwork-Array für Benachrichtigungen unterstützt Blob-URLs und Daten-URLs.
• Wenn kein Artwork definiert ist und es ein Symbolbild (mit <link rel=icon> angegeben) in der gewünschten Größe gibt, wird es in Medienbenachrichtigungen verwendet.
• Die Zielgröße für Artwork in Benachrichtigungen in Chrome für Android beträgt 512x512. Bei Low-End-Geräten ist das 256x256.
• Das title-Attribut des HTML-Medienelements wird im macOS-Widget „Aktuell wiedergegeben“ verwendet.
• Wenn die Medienressource eingebettet ist (z. B. in einem iFrame), müssen Informationen zur Media Session API aus dem eingebetteten Kontext festgelegt werden. Siehe Snippet unten.

<iframe id="iframe">
  <video>...</video>
</iframe>
<script>
  iframe.contentWindow.navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Never Gonna Give You Up',
    ...
  });
</script>

Du kannst den Medienmetadaten auch Informationen zu einzelnen Kapiteln hinzufügen, z. B. den Titel des Abschnitts, seinen Zeitstempel und ein Screenshot-Bild. So können Nutzer die Inhalte der Medien aufrufen.

navigator.mediaSession.metadata = new MediaMetadata({
  // title, artist, album, artwork, ...
  chapterInfo: [{
    title: 'Chapter 1',
    startTime: 0,
    artwork: [
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  }, {
    title: 'Chapter 2',
    startTime: 42,
    artwork: [
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  }]
});

Nutzern die Möglichkeit geben, die Wiedergabe zu steuern

Eine Mediensitzungsaktion ist eine Aktion (z. B. „Wiedergabe“ oder „Pause“), die eine Website für Nutzer ausführen kann, wenn sie mit der aktuellen Medienwiedergabe interagieren. Aktionen sind analog zu Ereignissen und funktionieren ähnlich. Wie bei Ereignissen werden Aktionen implementiert, indem Handler für ein geeignetes Objekt festgelegt werden, in diesem Fall eine Instanz von MediaSession. Einige Aktionen werden ausgelöst, wenn Nutzer die Schaltflächen eines Headsets, eines anderen Remote-Geräts oder einer Tastatur drücken oder mit einer Medienbenachrichtigung interagieren.

Da einige Aktionen für Mediensitzungen möglicherweise nicht unterstützt werden, wird empfohlen, beim Festlegen einen try…catch-Block zu verwenden.

const actionHandlers = [
  ['play',          () => { /* ... */ }],
  ['pause',         () => { /* ... */ }],
  ['previoustrack', () => { /* ... */ }],
  ['nexttrack',     () => { /* ... */ }],
  ['stop',          () => { /* ... */ }],
  ['seekbackward',  (details) => { /* ... */ }],
  ['seekforward',   (details) => { /* ... */ }],
  ['seekto',        (details) => { /* ... */ }],
  /* Video conferencing actions */
  ['togglemicrophone', () => { /* ... */ }],
  ['togglecamera',     () => { /* ... */ }],
  ['hangup',           () => { /* ... */ }],
  /* Presenting slides actions */
  ['previousslide', () => { /* ... */ }],
  ['nextslide',     () => { /* ... */ }],
];

for (const [action, handler] of actionHandlers) {
  try {
    navigator.mediaSession.setActionHandler(action, handler);
  } catch (error) {
    console.log(`The media session action "${action}" is not supported yet.`);
  }
}

Das Deaktivieren eines Aktions-Handlers für Mediensitzungen ist genauso einfach wie das Festlegen auf null.

try {
  // Unset the "nexttrack" action handler at the end of a playlist.
  navigator.mediaSession.setActionHandler('nexttrack', null);
} catch (error) {
  console.log(`The media session action "nexttrack" is not supported yet.`);
}

Einmal festgelegt, bleiben Aktions-Handler für Mediensitzungen während der Medienwiedergabe erhalten. Das ähnelt dem Ereignis-Listener-Muster, mit der Ausnahme, dass beim Bearbeiten eines Ereignisses das Standardverhalten des Browsers beendet wird und dies als Signal verwendet wird, dass die Website die Medienaktion unterstützt. Daher werden die Steuerelemente für Medienaktionen nur angezeigt, wenn der richtige Action-Handler festgelegt ist.

Wiedergabe / Pause

Die Aktion "play" gibt an, dass der Nutzer die Medienwiedergabe fortsetzen möchte, während "pause" angibt, dass er sie vorübergehend anhalten möchte.

Das Symbol „Wiedergabe/Pause“ wird immer in einer Medienbenachrichtigung angezeigt und die zugehörigen Medienereignisse werden automatisch vom Browser verarbeitet. Wenn Sie das Standardverhalten überschreiben möchten, verarbeiten Sie die Medienaktionen „Wiedergabe“ und „Pause“ wie unten gezeigt.

Der Browser kann beispielsweise beim Suchen oder Laden einer Website davon ausgehen, dass keine Medien abgespielt werden. In diesem Fall können Sie dieses Verhalten überschreiben, indem Sie navigator.mediaSession.playbackState auf "playing" oder "paused" festlegen. So bleibt die Website-Benutzeroberfläche mit den Steuerelementen für Medienbenachrichtigungen synchronisiert.

const video = document.querySelector('video');

navigator.mediaSession.setActionHandler('play', async () => {
  // Resume playback
  await video.play();
});

navigator.mediaSession.setActionHandler('pause', () => {
  // Pause active playback
  video.pause();
});

video.addEventListener('play', () => {
  navigator.mediaSession.playbackState = 'playing';
});

video.addEventListener('pause', () => {
  navigator.mediaSession.playbackState = 'paused';
});

Vorheriger Titel

Die Aktion "previoustrack" gibt an, dass der Nutzer entweder die aktuelle Medienwiedergabe von vorn beginnen möchte, wenn die Medienwiedergabe einen Anfang hat, oder zum vorherigen Element in der Playlist wechseln möchte, wenn die Medienwiedergabe eine Playlist hat.

navigator.mediaSession.setActionHandler('previoustrack', () => {
  // Play previous track.
});

Nächster Titel

Die Aktion "nexttrack" gibt an, dass der Nutzer die Medienwiedergabe zum nächsten Element in der Playlist springen möchte, sofern die Medienwiedergabe eine Playlist enthält.

navigator.mediaSession.setActionHandler('nexttrack', () => {
  // Play next track.
});

Beenden

Die Aktion "stop" gibt an, dass der Nutzer die Medienwiedergabe beenden und gegebenenfalls den Status löschen möchte.

navigator.mediaSession.setActionHandler('stop', () => {
  // Stop playback and clear state if appropriate.
});

Zurück-/Vorspulen

Die Aktion "seekbackward" gibt an, dass der Nutzer die Medienwiedergabezeit um einen kurzen Zeitraum zurückspulen möchte, während "seekforward" angibt, dass er die Medienwiedergabezeit um einen kurzen Zeitraum vorspulen möchte. In beiden Fällen bedeutet „kurz“ einige Sekunden.

Der im Action-Handler angegebene Wert „seekOffset“ ist die Zeit in Sekunden, um die die Medienwiedergabezeit verschoben werden soll. Wenn sie nicht angegeben ist (z. B. undefined), sollten Sie eine angemessene Zeitspanne verwenden (z. B. 10–30 Sekunden).

const video = document.querySelector('video');
const defaultSkipTime = 10; /* Time to skip in seconds by default */

navigator.mediaSession.setActionHandler('seekbackward', (details) => {
  const skipTime = details.seekOffset || defaultSkipTime;
  video.currentTime = Math.max(video.currentTime - skipTime, 0);
  // TODO: Update playback state.
});

navigator.mediaSession.setActionHandler('seekforward', (details) => {
  const skipTime = details.seekOffset || defaultSkipTime;
  video.currentTime = Math.min(video.currentTime + skipTime, video.duration);
  // TODO: Update playback state.
});

Zu einer bestimmten Zeit springen

Die Aktion "seekto" gibt an, dass der Nutzer die Medienwiedergabezeit auf eine bestimmte Zeit verschieben möchte.

Der im Action-Handler angegebene Wert für seekTime ist die Zeit in Sekunden, zu der die Medienwiedergabe fortgesetzt werden soll.

Der im Action-Handler angegebene boolesche Wert fastSeek ist „wahr“, wenn die Aktion mehrmals als Teil einer Sequenz aufgerufen wird und dies nicht der letzte Aufruf in dieser Sequenz ist.

const video = document.querySelector('video');

navigator.mediaSession.setActionHandler('seekto', (details) => {
  if (details.fastSeek && 'fastSeek' in video) {
    // Only use fast seek if supported.
    video.fastSeek(details.seekTime);
    return;
  }
  video.currentTime = details.seekTime;
  // TODO: Update playback state.
});

Wiedergabeposition festlegen

Die korrekte Anzeige der Position der Medienwiedergabe in einer Benachrichtigung ist ganz einfach. Dazu müssen Sie den Positionszeitraum einfach zum richtigen Zeitpunkt festlegen, wie unten gezeigt. Der Positionierungsstatus ist eine Kombination aus der Wiedergabegeschwindigkeit, der Dauer und der aktuellen Zeit.

Die Dauer muss angegeben und positiv sein. Die Position muss positiv sein und kleiner als die Dauer. Die Wiedergaberate muss größer als 0 sein.

const video = document.querySelector('video');

function updatePositionState() {
  if ('setPositionState' in navigator.mediaSession) {
    navigator.mediaSession.setPositionState({
      duration: video.duration,
      playbackRate: video.playbackRate,
      position: video.currentTime,
    });
  }
}

// When video starts playing, update duration.
await video.play();
updatePositionState();

// When user wants to seek backward, update position.
navigator.mediaSession.setActionHandler('seekbackward', (details) => {
  /* ... */
  updatePositionState();
});

// When user wants to seek forward, update position.
navigator.mediaSession.setActionHandler('seekforward', (details) => {
  /* ... */
  updatePositionState();
});

// When user wants to seek to a specific time, update position.
navigator.mediaSession.setActionHandler('seekto', (details) => {
  /* ... */
  updatePositionState();
});

// When video playback rate changes, update position state.
video.addEventListener('ratechange', (event) => {
  updatePositionState();
});

Sie können den Positionszeitraum ganz einfach auf null zurücksetzen.

// Reset position state when media is reset.
navigator.mediaSession.setPositionState(null);

Aktionen für Videokonferenzen

Wenn der Nutzer den Videoanruf in einem Bild-im-Bild-Fenster öffnet, werden im Browser möglicherweise Steuerelemente für das Mikrofon und die Kamera sowie für das Auflegen angezeigt. Wenn der Nutzer darauf klickt, werden die Aktionen für Videokonferenzen unten ausgeführt. Ein Beispiel finden Sie im Beispiel für Videokonferenzen.

Mikrofon ein-/ausschalten

Die Aktion "togglemicrophone" gibt an, dass der Nutzer das Mikrofon stummschalten oder die Stummschaltung aufheben möchte. Die setMicrophoneActive(isActive)-Methode teilt dem Browser mit, ob die Website das Mikrofon derzeit als aktiv betrachtet.

let isMicrophoneActive = false;

navigator.mediaSession.setActionHandler('togglemicrophone', () => {
  if (isMicrophoneActive) {
    // Mute the microphone.
  } else {
    // Unmute the microphone.
  }
  isMicrophoneActive = !isMicrophoneActive;
  navigator.mediaSession.setMicrophoneActive(isMicrophoneActive);
});

Kamera aktivieren oder deaktivieren

Die Aktion "togglecamera" gibt an, dass der Nutzer die aktive Kamera ein- oder ausschalten möchte. Die Methode setCameraActive(isActive) gibt an, ob die Website vom Browser als aktiv betrachtet wird.

let isCameraActive = false;

navigator.mediaSession.setActionHandler('togglecamera', () => {
  if (isCameraActive) {
    // Disable the camera.
  } else {
    // Enable the camera.
  }
  isCameraActive = !isCameraActive;
  navigator.mediaSession.setCameraActive(isCameraActive);
});

Beenden

Die Aktion "hangup" gibt an, dass der Nutzer einen Anruf beenden möchte.

navigator.mediaSession.setActionHandler('hangup', () => {
  // End the call.
});

Aktionen für die Präsentation von Folien

Wenn der Nutzer seine Folienpräsentation in einem Bild-im-Bild-Fenster öffnet, werden im Browser möglicherweise Steuerelemente zum Wechseln der Folien angezeigt. Wenn der Nutzer darauf klickt, werden sie von der Website über die Media Session API verarbeitet. Ein Beispiel finden Sie im Beispiel für die Präsentation von Folien.

Zurück

Die Aktion "previousslide" gibt an, dass der Nutzer bei der Präsentation von Folien zur vorherigen Folie zurückkehren möchte.

navigator.mediaSession.setActionHandler('previousslide', () => {
  // Show previous slide.
});

Weiter

Die Aktion "nextslide" gibt an, dass der Nutzer bei der Präsentation von Folien zur nächsten Folie wechseln möchte.

navigator.mediaSession.setActionHandler('nextslide', () => {
  // Show next slide.
});

Beispiele

Hier findest du einige Media Session-Beispiele mit der Blender Foundation und der Arbeit von Jan Morgenstern.

Ressourcen

• Media Session Spec: wicg.github.io/mediasession
• Probleme mit der Spezifikation: github.com/WICG/mediasession/issues
• Chrome-Fehler: crbug.com